Skip to content

Add event-driven drainCapReports and deprecate buildCapReport - #3

Merged
deluxe2 merged 1 commit into
mainfrom
feature/cap-report-emitter
Nov 11, 2026
Merged

deluxe2 merged 1 commit into
mainfrom
feature/cap-report-emitter

Conversation

@zerepolbap

Copy link
Copy Markdown
Collaborator

What and why

In co-simulation, the VQEG CAP-CSP pilot asked for a CAP report on every network step through buildCapReport. The shared-state audit log therefore grew with the step count instead of with player events. The pilot signaling spec says the player should report on state transitions, at most once per second per UE. This PR moves that rule into SFV.

  • SFVCapReportEmitter (src/core/SFVCapReport.js) emits a report when a stall starts or ends, when current_video_id changes, or when playable_buffer_s has moved by at least 1.0 s since the last report sent.
  • Reports are limited to one per second of session time per UE. A change inside the rate-limit window is coalesced into the first report allowed after the window has passed.
  • SFVSimulationController and SFVBrowserController gain drainCapReports(timeS, { final }), which returns [] or one report. final: true skips the rate limit, so the end state of a session is always reported.
  • The threshold defaults to DEFAULT_CAP_BUFFER_DELTA_S = 1.0 and can be overridden with config.capReport.bufferDeltaS.

Compatibility

buildCapReport is kept unchanged and marked @deprecated. It still returns a snapshot on every call and does not affect what drainCapReports emits. Its only known consumer is the pilot harness, which switches to drainCapReports in a matching pilot change.

Verification

  • npm run verify passes: ESLint, format:check, fixture and patch validation, 181 tests and the simulation scripts.
  • New tests in test/cap-report.test.js cover the emitter rules (first report, buffer threshold, stall and video edges, rate limit and coalescing, final flush) and a controller run in which a slow transport causes a real stall.
  • With the pilot pointed at this commit, its L0 mock session records, network-steps.jsonl and telemetry.jsonl are byte-identical to current main with per-step polling. CAP rows in shared-state.jsonl drop from 42 to 4 on the 0.2 s run and from 1,602 to 14 on an 8 s run.

…dCapReport

Add SFVCapReportEmitter, which emits a CAP report on stall edges, video
switches and playable-buffer changes of at least 1.0 s, rate-limited to
one report per second of session time per UE. Changes suppressed by the
rate limit are coalesced into the next allowed report. The final drain
bypasses the rate limit so terminal state is not lost.

Both controllers expose drainCapReports(timeS, { final }). The per-call
snapshot buildCapReport is kept unchanged and marked deprecated.

Co-authored-by: Cursor <cursoragent@cursor.com>
@deluxe2
deluxe2 merged commit e85ff66 into main Nov 11, 2026
1 check passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants